package com.kun.companion.core.context;

import com.kun.companion.core.context.annotation.PostConstruct;

/**
 * Bean初始化生命周期管理接口
 *
 * <p>实现此接口的类需定义Bean初始化阶段的逻辑，通常用于：
 * <ul>
 *   <li>依赖注入完成后执行数据预加载</li>
 *   <li>进行配置参数的合法性校验</li>
 *   <li>建立外部服务连接（如数据库、消息队列）</li>
 *   <li>注册监听器或初始化缓存数据</li>
 * </ul>
 * 容器（如Spring）会在Bean属性注入完成后、正式投入使用前调用此方法。</p>
 *
 * <p><b>实现要求：</b>
 * <ol>
 *   <li>应避免在init方法中进行耗时操作（超过1秒），如需可异步执行</li>
 *   <li>若初始化失败应抛出明确异常以阻断应用启动</li>
 *   <li>需确保方法幂等性（重复调用无副作用）</li>
 * </ol>
 *
 * @author gzc
 * @since 2025/1/27 2:52
 **/
public interface InitializingBean {

    /**
     * 执行初始化操作
     *
     * <p><b>调用时机：</b>
     * <ul>
     *   <li>在所有属性依赖注入完成后调用</li>
     *   <li>在{@link PostConstruct}注解方法之前调用</li>
     *   <li>在Bean正式加入容器可用之前调用</li>
     * </ul>
     *
     * <p><b>注意事项：</b>
     * <ul>
     *   <li>允许抛出检查异常，容器应捕获并终止启动流程</li>
     *   <li>不建议在此方法中直接依赖其他Bean的初始化状态</li>
     * </ul>
     * <p>
     * 示例：
     * <pre>{@code
     * public class DatabaseConfig implements InitializingBean {
     *     private DataSource dataSource;
     *
     *     public void init() {
     *         if (!dataSource.validateConfig()) {
     *             throw new IllegalStateException("数据库配置校验失败");
     *         }
     *         Connection conn = dataSource.getConnection(); // 初始化连接池
     *     }
     * }
     * }</pre>
     *
     * @throws IllegalStateException 当初始化条件不满足时
     * @throws Exception             初始化过程中发生的其他异常
     */
    void init() throws Exception;
}